Using Variables & Expressions

Variables and expressions allow you to customize an experiment or to dynamically control how the stimuli appear during your experiment. We recommend assigning descriptive names to the variables as they may be used in the legends, graph labels, or column headers in the Plotter Panel. Note that variables in upper case ALWAYS refer to system variables and that variable names should only contain alphabetic characters (ie with no numerals, punctuation marks, symbols or space).

IMPORTANT: Variable names may sometimes appear between brackets. The rule about brackets is to use them only when the variable specifies a value (e.g., when specifying a stimulus parameter, or inside expressions), and to not use them when indicating the variable name for control purpose (e.g., dependent variable in method and procedure properties).

Control Variables
Response Variables
Specifying Parameters with Variables
Defining Values with Expressions
Syntax of Mathematical Expressions
System-Defined Constants & Variables

Control Variables

Control variables are typically used to customize a session for each subject or to simplify the parameterization of the experiment. They should be the independent variables of your experimental design. Control variables are declared either under the "Control Settings" tab of the "Experiment" events or the "Conditions" tab of "Method" events when creating experimental conditions.

Declaring independent variables in "Control Settings"

A table is available under "Control Settings" to declare independent variables:

An unlimited number of variables can be entered in the table, along with their values and locking status:

Each variable can either specify:

• a single numerical value (e.g. as in the above example with the 'coherence' and 'contrast' variables):

  ' number '

• values from which the variable is randomly assigned, that can take several forms:
  • a set of numerical values separated by a comma (e.g. the 'direction' variable taking the value -1 or 1):

    ' val1, val2 , ..., valn '

  • a continuous range with minimum and maximum separated by a colon (e.g. the 'sf' variable taking any real value between 1. and 6.):

    ' minimum value : maximum value '

  • a discrete range defined by a minimum value, the number of samples, and a maximum value separated by colons (e.g. the 'x' variable taking one of the 6 uniformly sampled values between -10 and 10 inclusive in increments of 4):

    ' minimum value : step : maximum value '

  Each of these random formats can be prefixed with a probability value between parentheses to specify the probability of change between the generation of 2 successive random values:
  
  ' (probability) val1, val2, ..., valn '
  
  ' (probability) minimum value : maximum value '
  
  ' (probability) minimum value : step : maximum value'

Note that random variables take new values each time they are used. Hence one should not assume identical values when the same random variable specifies several parameters of the same stimulus (see Defining Values with Expressions below and the use of the $ prefix to access the last variable value without generating a new one).

The locking status indicates whether the variable values can also be specified as subject-specific values at each start of an experiment session. In the example above, only the unlocked variables 'coherence' and 'contrast' can be modified in the "Session Information" panel when running the experiment:

The subject-specific values are shown in the “Subject-Specific Parameters” table where they can be edited, and are used instead of the default values specified in the “Independent Variables” table under the "Control Settings" tab of the Experiment Properties panel.

Declaring independent variables in "Conditions" method events

Control variables can also be specified when creating "Condition" events (see "Conditions" tab of "Method" event). Several variables can be defined along with multiples values to specify each experimental condition as illustrated below:

In the example above, two variables are defined for the condition named "Condition 1" selected in the "Conditions" table: 'size' and 'sf'. The selected variable in the "Variables" table, 'size', can take any of the specified values in the "Values" table ('2', '4' or '8'). Note that these variables values have to be specified with scalars (ie: expressions are not supported yet).

It is important to note as well that independent variables should be declared only once in your experiment design: an error will be emitted at run-time if the same variable is declared both in the "Control Settings" of the "Experiment" events and inside a "Condition" event.

Response Variables

Methods and procedures typically modify the stimuli properties based on the subject's responses and the stimuli intervals. Response variables should be the dependent variables of your experimental design. In each panel where the selection of a response variable is required, a selection box similar to the one shown below appears:

Once a dependent variable is declared, it can then be used to specify some stimulus properties. Failing to correctly specify the response variables and their instances in stimuli parameters (see Specifying Parameters with Variables below) will result in incorrect or undefined control of the stimuli parameters. However, warnings displayed in the "Experiment log" are likely to provide clues about the abnormal behavior of the experiment. Consequently, it is crucial to verify that no warning or error has been logged after the experiment is terminated (remember that pressing the ESC key on the primary keyboard will abort the experiment). For example if the same variable is declared as both a control and response variable, an error will be emitted at run-time.

Specifying Parameters with Variables

Once a variable has been declared either as a control or response variable, it should be used to specify the value taken by a parameter in the different events. Most event parameters can be edited through a text field. To specify a parameter value with a variable, simply replace the numerical value in its text field with the variable name in brackets (ie: [variable]). The variable name can also be chosen by control-clicking on the parameter text field and selecting the variable from the contextual menu (both user-defined variables and system variables are available). The text field is then automatically filled in with the variable in brackets as illustrated below:

Note that for randomly-defined variables (see "Control Variables" above), the reference to its value through the [variable] format will trigger the generation of a new random value at run-time. This can be a problem when using the same random variable to specify different properties of the same stimulus or keeping some properties synchronized across different stimuli, because one would expect the same value to be used. To prevent this problem, one can use the format [$variable] (note the $ symbol before the variable name) to indicate to use the last generated value rather than generating a new random value. In other words to ensure a correct behavior, the first reference to a random variable for a given trial should be done through the format [variable] and all subsequent references to this variable should be done through the format [$variable].

For stimuli event, the variable format can also take optionally the form [variable:defaultvalue] where defaultvalue is the value used by default to generate the stimulus preview. If not specified, the parameter value is 0 by default. Note that if an appropriate default value is not provided, the stimulus preview may either lead to an unexpected result or a warning sign due to a computation error (eg: a division by zero). So it is highly recommend to always provide explicit default values for your stimulus parameters to check the validity of your stimuli during your experimental design.

In addition to single numerical values and variables, parameter values can be specified with complex mathematical expressions as described in the next section using the "Math Editor" (also available from the contextual menu).

Tip to remember: control-click on any parameter text field to access the list of available variables or the math editor from the contextual menu.

Defining Values with Expressions

Psykinematix allows most of the stimuli parameters to be defined as mathematical expressions of arbitrary complexity. These expressions may depend on dependent or independent variables of the experimental design, be a function of time to create dynamic stimuli, or even be randomly selected from a specified range. The creation of Custom Stimuli relies entirely on the evaluation of a sequence of such mathematical expressions with the specificity that they make use of built-in 2D and temporal variables (x, y, r, theta, time). These computing capabilities make Psykinematix a powerful and very versatile stimulus generator.

Expressions are used to specify the numerical values taken by most stimuli parameters as well as the decision evaluations in procedures. Valid formats for expressions are:

• a single numerical value (scalar):

  ' number '

• a variable name between brackets [ ]:
  
  ' [variable] ', '[variable:defaultvalue]', '[$variable]' or '[$variable:defaultvalue]'


• a single mathematical formula (see syntax and available functions below). This formula can include variables with the above formats.
  


• an expression between curly braces { } to specify properties for individual elements in multi-element stimuli (RDK, MEF and SSS):
  
  { expression }

  When the expression is surrounded with the { } symbols, the expression is evaluated independently for each element that composes the multi-element stimulus. This capability is only available to the speed and direction parameters in RDK stimuli, the element rotation in MEF and SSS, and the distribution coordinates in SSS. The expression between { } can also refer to the position of each element using the x and y Cartesian coordinates, the r and theta polar coordinates relative to the center of their embedding zone, or the special variables k and i that refer to the local curvature and index of each element respectively:
  
  {i}, {x}, {y}, {r}, {theta} or {k}

• a complex expression made of mathematical formulas separated by semicolons: local variables can be assigned and the expression value results from the evaluation of the last formula without assignment as illustrated in the example below.
  
  Note that by selecting the "Editor" command in the contextual menu opened by control-clicking on a parameter text field, the expression is presented inside a Math palette where it can be more easily edited (semicolons are converted to new lines for better legibility). The expression background turns to red when it is syntactically incorrect, and the changes made in the palette are only reflected in the parameter text field when its syntax is correct. Predefined formulas can be selected using the pop-up menu and appended to the edited expression (time-varying expressions can be also graphed inside this Math palette, see below).
  

Time-varying expressions.

Stimuli parameters can be set as time-varying. Several formats are available for specifying time-varying expressions:

• implicitly as a function of time, with three possible forms using the colon separator to express the samples range and with the dynamic factor between parentheses:

  min : max(speed)

  min : nbsamples : max(duration)

  sample :: (duration)

  where min and max define the starting and ending values of the parameters, speed is the rate of change (represented in units per second), nbsamples defines the number of samples between the starting and ending values (inclusive), and duration defines the duration of each sample in seconds. In the third form, sample denotes the expression to be evaluated every duration period (Tip: this form is particularly useful for generating temporal sequence of random values).

• explicitly through a time-varying mathematical expression by using the system-defined variable [TIME] that specifies the time relative to the stimulus onset (time should be only used in the definition of custom stimuli). If necessary, the duration of the currently-edited stimulus can be accessed through the system-defined variable [DURATION].
  
  Note that a time-varying expression edited in the Math palette is automatically plotted in the graphing window below it (to access the palette control-click on the parameter text field and select the "Editor" command in the contextual menu). Each time sample corresponds to a video frame at the frame rate specified for the current experiment (see "Display Settings" tab of the Experiment Properties panel). As illustrated below, there are some useful predefined time-varying formulas available though the pop-up menu that can be appended to the edited expression. The plot can be printed, copied to the pasteboard or save to a file by control-clicking onto the graph.

Syntax of Mathematical Expressions

A single mathematical expression should follow the <expression> syntax which can have any of the following forms (parentheses can be used to specify the order of operations):

<expression> :=

<numerical value>

<constant>

<variable>

<function>(<expression 1>, ... , <expression n>)

<expression 1> <operator> <expression 2>

where <variable> is either:

[<name>]         any user- or system-defined variable (note that system-defined variables are always in uppercase)

<parameter>    a parameter name defined in the Parameter Table for Custom Stimuli

<reserved>      a reserved 2D array coordinate only available for Custom Stimuli (x, y, r, theta)

<constant> is any of the predefined scalar constants:

<operator> is any of the following elementary operators:

<function> is any of the following built-in functions:

The following 2D functions are only available for Custom Stimuli:

Note that most 2D operations are applied on a pixel basis when at least one of the operands consists of a 2D array as it is the case for Custom Stimuli. The evaluation of the expressions is also highly optimized, typically several times faster than its Matlab® equivalent.

Expressions specific to trigger information:

The following 2 formats can only be used when specifying some trigger information sent to an external device (see Trigger section):

System-Defined Constants & Variables

Psykinematix uses special built-in constants and variables to keep track of particular values. All system-defined constants and variables are in uppercase to differentiate them from user-defined variables.

System-defined constants

System-defined constants are those values that do not change inside an experimental session and that depend on the experimental setup. Here is a list of these constants:

System-defined dependent variables

System-defined dependent variables are read-only variables whose values change inside an experimental session and that depend on some properties of the experimental events currently run or edited. Here is a list of these read-only variables:

System-defined independent variables

System-defined independent variables are writable variables whose values can be specified in the independent variable table of the Experiment Control Settings. These variables allow the customization of some experimental aspects that do not have a counterpart in the graphical user interface. Here is a list of these writable variables:

© 2006-2024 KyberVision Japan LLC. All rights reserved.